/*!
 * This method generates statistics based on an arbitrarily sized input array of
 * class grades.
 *
 *  Copyright (C) 2011  Anthony Wertz.
 *
 *  This program is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
#ifndef _StatGen_h_
#define _StatGen_h_

/*! Structure representing the grades earned by a group of students. */
struct GradeType
{
  unsigned int  studentID;      //!< An identifier to match students to grades.
  double        grade;          //!< The earned grade.
  
  /*! Default initializer. */
  GradeType( void ) :
    studentID( 0 ),
    grade( 0.0 )
  {
    //
  }
  
  /*! Initialized. */
  GradeType( const unsigned int studentID, const double grade ) :
    studentID( studentID ),
    grade( grade )
  {
    //
  }
};

/*!
 * Determines the average grade from a list of test scores and returns the
 * number of students scoring above and below the average.
 *
 * @param[in] grades The grades to analyze. Assumed to be unsorted.
 * @param[in] numberOfGrades The number of grades in the list to analyze.
 * @param[out] numberOfStudentsAtOrBelowAverage Returns the number of students
 *    who scored below average or exactly equal to average.
 * @param[out] numberOfStudentsAboveAverage Returns the number of students who
 *    scored above average.
 *
 * @return Returns true if 0 or more grades were successfully analyzed, false if
 *    an invalid list was supplied.
 *
 * @note In the event an invalid list is supplied, the "numberOfStudents*"
 *    parameters will not be modified.
 */
bool StatGen(
  const GradeType * const grades,
  const unsigned int numberOfGrades,
  unsigned int & numberOfStudentsAtOrBelowAverage,
  unsigned int & numberOfStudentsAboveAverage );

#endif

